home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / internet / irc_i_dodatki / eggdrop / eggdrop11.lha / tcl-commands.doc < prev    next >
Text File  |  1997-01-15  |  43KB  |  1,123 lines
  1. This is an exhaustive list of all the Tcl commands added to eggdrop.  All
  2. of the normal Tcl built-in commands are still there, of course.  But you
  3. can also use these to manipulate features of the bot.  They are listed
  4. according to category.
  5.  
  6. NOTICE:  This list is accurate for the v1.1 series of eggdrop!
  7. SCRIPTS WHICH WERE WRITTEN FOR v0.9 OR v1.0 WILL PROBABLY NOT WORK WITHOUT
  8. MODIFICATION.  Commands which have been changed in the v1.1 series (or are
  9. just new commands) are marked with vertical bars on the left.
  10.  
  11.  
  12.  
  13. *** OUTPUT COMMANDS ***
  14.  
  15.   putserv <text>
  16.     sends text to the server, like 'dump' (intended for direct server
  17.       commands); output is queued so that you won't flood yourself off
  18.       the server
  19.     returns: nothing
  20.  
  21.   puthelp <text>
  22.     sends text to the server like 'putserv', but uses a different queue
  23.       (intended for sending messages to channels or people)
  24.     returns: nothing
  25.  
  26.   putlog <text>
  27.     sends text to the log for any channel, marked as 'misc' (o)
  28.     returns: nothing
  29.  
  30.   putcmdlog <text>
  31.     sends text to the log for any channel, marked as 'command' (c)
  32.     returns: nothing
  33.  
  34.   putxferlog <text>
  35.     sends text to the log for any channel, marked as 'file-area' (x)
  36.     returns: nothing
  37.  
  38.   putloglev <level(s)> <channel> <text>
  39. |   sends text to the log, tagged with all of the valid levels given (use
  40. |     "*" to indicate all log levels)
  41.     returns: nothing
  42.  
  43.   dumpfile <nick> <filename>
  44.     dumps out a file from the text directory to a user on IRC via
  45.       msg (one line per msg); %( and %[ won't work because it will
  46.       assume the user is not an op or master
  47.  
  48.  
  49. *** USER RECORD MANIPULATION COMMANDS ***
  50.  
  51.   countusers
  52.     returns: number of users in the bot's database
  53.  
  54.   validuser <handle>
  55.     returns: "1" if a user by that name exists; '0' otherwise
  56.  
  57.   finduser <nick!user@host>
  58.     finds the user record which most closely matches the given user@host
  59.     returns: the handle found, or "*" if none
  60.  
  61.   userlist [flags]
  62.     returns: a list of the handles of users on the bot -- if you specify
  63.       flags, only users who have ALL of those flags will be in the list
  64.  
  65.   passwdok <handle> <pass>
  66.     checks the password given against the user's password -- if the user has
  67.       not set a password, will always return "1"; check against the password
  68.       "" (a blank string) to find out if a user has no password set
  69.     returns: "1" if password matches for that user; "0" if not
  70.  
  71.   chpass <handle> <pass>
  72.     attempts to set a new password for a user, if that user exists
  73.  
  74. | chnick <old-handle> <new-handle>
  75. |   changes a user's handle
  76. |   returns: "1" on success; "0" if the handle is already used, the handle
  77. |     is invalid, or the user can't be found
  78.  
  79. | chattr <handle> [changes [channel]]
  80. |   changes the attributes for a user record, if you include any -- changes
  81. |     are of the form "+f", "-o", "+dk", "-o+d", etc; if a channel is 
  82. |     specified, the channel-specific flags for that channel are altered
  83. |   returns: new flags for the user (if you made no changes, returns current
  84. |     flags); if a channel was specified, the channel-specific flags for that
  85. |     channel are returned -- returns "*" if that user does not exist
  86.  
  87.   matchattr <handle> <flags>
  88.     returns: "1" if the specified user has ALL the flags requested
  89.  
  90. | matchchanattr <handle> <flags> <channel>
  91. |   returns: "1" if the specified user has ALL the channel-specific flags
  92. |     requested for that channel
  93.  
  94.   adduser <handle> <hostmask>
  95.     creates a new user entry with the handle and hostmask given (with no pass-
  96.       word, and the default flags)
  97.     returns: "1" if successful, "0" if it already existed
  98.  
  99.   addbot <handle> <address>
  100.     creates a new bot entry with the handle and bot linking address given
  101.       (with no password and no flags)
  102.     returns: "1" if successful, "0" if it already existed
  103.  
  104.   deluser <handle>
  105.     attempts to erase a user record with that handle
  106.     returns: "1" if successful, "0" if no such user exists
  107.  
  108.   addhost <handle> <hostmask>
  109.     adds a hostmask to the hostmask list for a user
  110.     returns: nothing
  111.  
  112.   delhost <handle> <hostmask>
  113.     deletes a hostmask from a user's hostmask list
  114.     returns: "1" on success, "0" if that hostmask wasn't in the list or the
  115.       user does not exist
  116.  
  117.   gethosts <handle>
  118.     returns: the hostmask list for that user if there are any, "none" if
  119.       the user exists but there are no hostmasks, "" if the user doesn't
  120.       exist
  121.  
  122.   getinfo <handle>
  123.     returns: info line for that user ("" if none exists); always returns
  124.       an empty string for bots; if the user's info line is locked (ie, that
  125.       user can't change their info line), the first character of the info
  126.       line will be '@'
  127.  
  128.   getaddr <handle>
  129.     returns: link address for that bot ("" if none exists); always returns
  130.       an empty string for non-bots
  131.  
  132.   getdccdir <handle>
  133.     returns: dcc directory for that user ("" if none exists)
  134.  
  135.   getcomment <handle>
  136.     returns: comment for that user ("" if none exists)
  137.  
  138.   getemail <handle>
  139.     returns: email address for that user ("" if none exists)
  140.  
  141.   getxtra <handle>
  142.     returns: xtra info for a user ("" if none exists)
  143.  
  144. | getlaston <handle> <channel>
  145. |   returns: last time that user was on that channel (in unixtime format);
  146. |     may return 0 if the user has never been on that channel or if there
  147. |     is no such user
  148.  
  149.   setinfo <handle> <info>
  150.     sets the info line for a user
  151.     returns: nothing
  152.  
  153.   setdccdir <handle> <dccdir>
  154.     sets the dcc directory for a user
  155.     returns: nothing
  156.  
  157.   setcomment <handle> <comment>
  158.     sets the comment for a user
  159.     returns: nothing
  160.  
  161.   setemail <handle> <email>
  162.     sets the email address for a user
  163.     returns: nothing
  164.  
  165.   setxtra <handle> <xtrastuff>
  166.     sets the xtra info for a user (this field exists specifically to be used
  167.       by Tcl scripts)
  168.     returns: nothing
  169.  
  170. | setlaston <handle> <channel> [timestamp]
  171. |   sets the last time the user was on the channel to the current time (or
  172. |     the time you specify, in unixtime)
  173. |   returns: nothing
  174.  
  175. | newchanban <channel> <ban> <creator> <comment> [lifetime] [options]
  176. |   adds a ban to the enforced ban list of a channel; creator is given
  177. |     credit for the ban in the ban list; lifetime is specified in
  178. |     minutes; if lifetime is not specified, ban-time (usually 60) is
  179. |     used; setting the lifetime to 0 makes it a permanent ban; valid
  180. |     options are:
  181. |       sticky     forces the ban to be always active on a channel, even
  182. |                    with dynamic bans on
  183. |       none       (no effect)
  184. |   returns: nothing
  185.  
  186. | newban <ban> <creator> <comment> [lifetime] [options]
  187. |   adds a ban to the global ban list (which takes effect on all channels);
  188. |     other arguments work exactly like newchanban
  189. |   returns: nothing
  190.  
  191.   killchanban <channel> <ban>
  192.     removes a ban from the enforced ban list for a channel
  193.     returns: "1" if successful, "0" otherwise
  194.  
  195.   killban <ban>
  196.     removes a ban from the global ban list
  197.     returns: "1" if successful, "0" otherwise
  198.  
  199.   isban <ban> [channel]
  200.     returns: "1" if that ban is in the global ban list, "0" otherwise; if
  201.       a channel is specified, that channel's ban list is checked too
  202.   
  203.   ispermban <ban> [channel]
  204.     returns: "1" if that ban is in the global ban list AND is marked as
  205.       permanent, "0" otherwise; if a channel is specified, that channel's
  206.       ban list is checked too
  207.  
  208.   matchban <nick!user@host> [channel]
  209.     returns: "1" if that user address matches a ban in the global ban list,
  210.       "0" otherwise; if a channel is specified, that channel's ban list is
  211.       checked too
  212.  
  213.   banlist [channel]
  214.     returns: list of global bans, or (if a channel is specified) list of
  215.       channel-specific bans; each entry is itself a list, containing:
  216.       hostmask, comment, expiration timestamp, time added, last time
  217.       active, and creator (the three timestamps are in unixtime format)
  218.  
  219.   newignore <hostmask> <creator> <comment> [lifetime]
  220.     adds an entry to the ignore list; creator is given credit for the
  221.       ignore; lifetime is how many minutes until the ignore expires and
  222.       is removed; if lifetime is not specified, ignore-time (usually 60)
  223.       is used; setting the lifetime to 0 makes it a permanent ignore
  224.     returns: nothing
  225.  
  226.   killignore <hostmask>
  227.     removes an entry from the ignore list
  228.     returns: "1" if successful, "0" otherwise
  229.  
  230.   ignorelist
  231.     returns: list of ignores; each entry is itself a list, containing:
  232.       hostmask, comment, expiration timestamp, time added, and creator
  233.       (the three timestamps are in unixtime format)
  234.  
  235.   isignore <hostmask>
  236.     returns: "1" if the ignore is in the list, "0" otherwise
  237.  
  238.   save
  239.     writes the userfile to disk
  240.     returns: nothing
  241.  
  242.   reload
  243.     loads the userfile from disk (replacing whatever's in memory)
  244.     returns: nothing
  245.  
  246. | backup
  247. |   makes a simple backup of the userfile that's on disk
  248. |   returns: nothing
  249.  
  250.   getting-users
  251.     returns: "1" if the bot is currently downloading a userfile from
  252.       a sharebot (and hence, user records are about to drastically
  253.       change), "0" if not
  254.  
  255.  
  256. *** CHANNEL COMMANDS ***
  257.  
  258.   channel add <name> <option-list>
  259.     adds a channel record for the bot to monitor; the full list of possible
  260.       options is given in the "lamestbot" sample config file; note that the
  261.       channel options must be in a list (enclosed in {})
  262.     returns: nothing
  263.  
  264.   channel set <name> <options...>
  265.     sets options for the channel specified; the full list of possible
  266.       options is given in the "lamestbot" sample config file
  267.     returns: nothing
  268.  
  269.   channel info <name>
  270.     returns: list of info about that channel record: enforced mode, idle
  271.       kick limit, need-op script, need-invite script, and then various
  272.       +/- options as seen in the config file
  273.  
  274.   channel remove <name>
  275.     destroys a channel record for the bot and makes the bot no longer
  276.       monitor that channel
  277.     returns: nothing
  278.  
  279.   channels
  280.     returns: list of the channels the bot is monitoring (or trying to)
  281.  
  282.   botisop <channel>
  283.     returns: "1" if the bot is an op on that channel; "0" otherwise
  284.  
  285.   isop <nickname> <channel>
  286.     returns: "1" if someone by that nickname is on the channel and has chop;
  287.       "0" otherwise
  288.  
  289.   isvoice <nickname> <channel>
  290.     returns: "1" if someone by that nickname is on the channel and has voice
  291.       (+v); "0" otherwise
  292.  
  293.   onchan <nickname> <channel>
  294.     returns: "1" if someone by that nickname is on the bot's channel; "0"
  295.       otherwise
  296.  
  297.   nick2hand <nickname> <channel>
  298.     returns: handle of the person on the channel with that nickname, if
  299.       someone by that nickname is on the channel; "" otherwise
  300.  
  301.   handonchan <handle> <channel>
  302.     returns: "1" if the the user@host for someone on the channel matches
  303.       for the handle given; "0" otherwise
  304.  
  305.   hand2nick <handle> <channel>
  306.     returns: nickname of the first person on the channel whose user@host
  307.       matches that handle, if there is one; "" otherwise
  308.  
  309.   ischanban <ban> <channel>
  310.     returns: "1" if that is a ban on the bot's channel
  311.  
  312.   chanbans <channel>
  313.     returns: a list of the current bans on the channel
  314.  
  315. | resetbans <channel>
  316. |   removes all bans on the channel that aren't in the bot's ban list, and
  317. |     refreshes any bans that should be on the channel but aren't
  318. |   returns: nothing
  319.  
  320.   getchanhost <nickname> <channel>
  321.     returns: user@host of that person if they are on the channel; {} otherwise
  322.  
  323.   onchansplit <nick> <channel>
  324.     returns: "1" if that nick is split from the channel; "0" otherwise
  325.  
  326.   chanlist <channel> [flags]
  327.     returns: list of nicknames currently on the bot's channel that have all
  328.        of the flags specified; if no flags are given, all of the nicknames
  329.        are returned
  330.  
  331.   getchanidle <nickname> <channel>
  332.     returns: number of minutes that person has been idle; "0" if the speci-
  333.       fied user isn't even on the channel
  334.  
  335.   getchanmode <channel>
  336.     returns: string of the type "+ntik key" for the channel specified
  337.  
  338.   jump [server [port [password]]]
  339.     jumps to the server specified, or (if none is specified) the next server
  340.       in the list
  341.     returns: nothing
  342.  
  343.   pushmode <channel> <mode> [arg]
  344.     sends out a channel mode change (ex: pushmode #lame +o goober) through
  345.       the bot's queueing system; all the mode changes will be sent out at
  346.       once (combined into one line as much as possible) after the script
  347.       finishes, or when 'flushmode' is called
  348.  
  349.   flushmode <channel>
  350.     forces all previously pushed channel mode changes to go out right now,
  351.       instead of when the script is done (just for the channel specified)
  352.  
  353.  
  354. *** DCC COMMANDS ***
  355.  
  356.   putdcc <idx> <text>
  357.     sends text to the dcc user indicated
  358.     returns: nothing
  359.  
  360.   dccbroadcast <message>
  361.     sends your message to everyone on the party line on the bot net, in the
  362.       form "*** <message>" for local users, and "*** [Bot] <message>" for
  363.       users on other bots
  364.  
  365.   dccputchan <channel> <message>
  366.     sends your message to everyone on a certain channel on the bot net, in
  367.       a form exactly like dccbroadcast does -- valid channels are 0 thru 99999
  368.     returns: nothing
  369.  
  370.   dccsimul <idx> <text...>
  371.     simulates text typed in by the dcc user specified -- note that in v0.9,
  372.       this only simulated commands; now a command must be preceded by a '.'
  373.       to be simulated
  374.     returns: nothing
  375.  
  376.   hand2idx <handle>
  377.     returns: the idx (a number greater than or equal to zero) for the user
  378.       given, if she is on the party line in chat mode (even if she is currently
  379.       on a channel or in chat off), the file area, or in the control of a
  380.       script; "-1" otherwise -- if the user is on multiple times, the oldest
  381.       idx is returned
  382.  
  383.   idx2hand <idx>
  384.     returns: handle of the user with that idx
  385.  
  386. | valididx <idx>
  387. |   returns: "1" if the idx currently exists; "0" if not
  388.  
  389.   getchan <idx>
  390.     returns: the current party line channel for a user on the party line --
  391.       "0" indicates he's on the group party line, "-1" means he has chat off,
  392.       and a value from 1 to 99999 is a private channel
  393.  
  394.   setchan <idx> <channel>
  395.     sets a party line user's channel rather suddenly (the party line user
  396.       is not notified that she is now on a new channel); a channel name
  397.       can be used (provided it exists)
  398.     returns: nothing
  399.  
  400.   console <idx> [channel] [console-modes]
  401.     changes a dcc user's console mode, either to an absolute mode (like "mpj")
  402.       or just adding/removing flags (like "+pj" or "-moc" or "+mp-c"); the
  403.       user's console channel view can be changed also (as long as the new
  404.       channel is defined in the bot)
  405.     returns: a list containing the user's (new) channel view, and (new)
  406.       console mode, or nothing if that user isn't currently in dcc chat
  407.  
  408.   echo <idx> [status]
  409.     turns a user's echo on or off; the status has to be a 1 or 0
  410.     returns: new value of echo for that user (or the current value, if
  411.       status was omitted)
  412.  
  413.   putbot <bot-nick> <message>
  414.     sends a message across the bot-net to another bot; if no script intercepts
  415.       the message on the other end, the message just vanishes
  416.     returns: nothing
  417.  
  418.   putallbots <message>
  419.     broadcasts a message across the bot-net to all currently connected bots
  420.     returns: nothing
  421.  
  422.   killdcc <idx>
  423.     kills a party-line or file area connection, rather abruptly
  424.     returns: nothing
  425.  
  426.   bots
  427.     returns: list of the bots currently connected to the botnet
  428.  
  429.   dccused
  430.     returns: number of dcc connections currently in use
  431.  
  432.   dcclist
  433.     returns: list of active dcc connections that are in the chat area, the
  434.       file area, or a script; each item in the list will be a sublist with
  435.       four elements: idx, nickname, hostname, and type; type will be "chat",
  436.       "files", or "script" (or "socket" for connections that haven't been
  437.       put under 'control' yet)
  438.  
  439.   whom <chan>
  440.     returns: list of people on the botnet who are on that channel (0 is
  441.       the default party line); each item in the list will be a sublist
  442.       with six elements: nickname, bot, hostname, access flag ('-', '@',
  443.       '+', or '*'), minutes idle, and away message (blank if the user is
  444.       not away)
  445.  
  446.   getdccidle <idx>
  447.     returns: number of seconds the dcc chat/file system/script user has
  448.       been idle
  449.  
  450.   getdccaway <idx>
  451.     returns: away message for a dcc chat user (or "" if the user is not
  452.       set away)
  453.  
  454.   setdccaway <idx> <message>
  455.     sets a party line user's away message and marks them away; if set to
  456.       "", the user is marked un-away
  457.     returns: nothing
  458.  
  459.   assoc <chan> [name]
  460.     sets the name associated with a botnet channel, if you specify one
  461.     returns: current name for that channel, if any
  462.  
  463.   killassoc <chan>
  464.     removes the name associated with a botnet channel, if any exists
  465.     returns: nothing
  466.  
  467.   connect <host> <port>
  468.     makes an outgoing connection attempt and creates a dcc entry for it;
  469.       a 'control' command should be used immediately after a successful
  470.       'connect' so no input is lost
  471.     returns: idx of the new connection
  472.  
  473. | listen <port> <type> [options]
  474. |   opens a listening port to accept incoming telnets; type must be one of
  475. |     "bots", "all", "users", "script", or "off":
  476. | listen <port> bots [mask]
  477. |   accepts connections from bots only; the optional mask is used to identify
  478. |     permitted bot names
  479. |   returns: port #
  480. | listen <port> users [mask]
  481. |   accepts connections from users only (no bots); the optional mask is used
  482. |     to identify permitted nicknames
  483. |   returns: port #
  484. | listen <port> all [mask]
  485. |   accepts connections from anyone; the optional mask is used to identify
  486. |     permitted nicknames/botnames
  487. |   returns: port #
  488. | listen <port> script <proc>
  489. |   accepts connections which are immediately routed to a proc; the proc
  490. |     is called with one parameter: the idx of the new connection
  491. |   returns: port #
  492. | listen <port> off
  493. |   stop listening at a port
  494. |   returns: nothing
  495.  
  496.   dccdumpfile <idx> <filename>
  497.     dumps out a file from the text directory to a dcc chat user; %( and
  498.       %[ will work (unlike 'dumpfile')
  499.  
  500.  
  501. *** FILE SYSTEM COMMANDS ***
  502.  
  503.   setpwd <idx> <dir>
  504.     changes the directory of a file system user, in exactly the same way
  505.       as a 'cd' command would (ie, the directory can be specified relative
  506.       or absolute)
  507.     returns: nothing
  508.  
  509.   getpwd <idx>
  510.     returns: the current directory of a file system user
  511.  
  512.   getfiles <dir>
  513.     returns: list of files in the directory given; the directory is relative
  514.       to dcc-path
  515.  
  516.   getdirs <dir>
  517.     returns: list of subdirectories in the directory given; the directory
  518.       is relative to dcc-path
  519.  
  520.   dccsend <filename> <ircnick>
  521.     attempts to start a dcc file transfer to the given nick; the filename must
  522.       be specified either by full pathname or in relation to the bot's startup
  523.       directory
  524.     returns: "0" on success, "1" if the dcc table is full (too many con-
  525.       nections), "2" if it can't open a socket for the transfer, "3" if the
  526.       file doesn't exist, and "4" if the file was queued for later transfer
  527.       (which means that person has too many file transfers going right now)
  528.  
  529.   filesend <idx> <filename> [ircnick]
  530.     like dccsend, except it operates for a current filesystem user, and
  531.       the filename is assumed to be a relative path from that user's
  532.       current directory
  533.     returns: "0" on failure; "1" on success (either an immediate send
  534.       or a queued send)
  535.  
  536.   setdesc <dir> <file> <desc>
  537.     sets the description for a file in a file system directory; the
  538.       directory is relative to the dcc-path
  539.     returns: nothing
  540.  
  541.   getdesc <dir> <file>
  542.     returns: the description for a file in the file system, if one
  543.       exists
  544.  
  545.   setowner <dir> <file> <handle>
  546.     changes the owner for a file in the file system; the directory is
  547.       relative to the dcc-path
  548.     returns: nothing
  549.  
  550.   getowner <dir> <file>
  551.     returns: the owner of a file in the file system
  552.  
  553.   setlink <dir> <file> <link>
  554.     creates or changes a linked file (a file that actually exists on
  555.       another bot); the directory is relative to dcc-path
  556.     returns: nothing
  557.  
  558.   getlink <dir> <file>
  559.     returns: the link for a linked file, if it exists
  560.  
  561.   getfileq <handle>
  562.     returns: list of files queued by someone; each item in the list will be
  563.       a sublist with two elements: nickname the file is being sent to, and
  564.       the filename
  565.  
  566.  
  567. *** MISCELLANEOUS COMMANDS ***
  568.  
  569.   bind <type> <attr(s)> <command-name> <proc-name>
  570.     adds a new keyword command to the bot; valid types are listed below; the
  571.       <attr(s)> are the flags that a user must have to trigger this command;
  572.       the <command-name> for each type is listed below; <proc-name> is the
  573.       name of the Tcl procedure to call for this command (see below for the
  574.       format of the procedure call)
  575.     returns: name of the command that was added
  576.  
  577.   unbind <type> <attr(s)> <command-name> <proc-name>
  578.     removes a previously-made binding
  579.     returns: name of the command that was removed
  580.  
  581.   logfile [<modes> <channel> <filename>]
  582.     creates a new logfile, which will log the modes given for the channel
  583.       listed -- or, if no logfile is specified, just returns a list of
  584.       logfiles; "*" can be used to mean all channels; you can also change
  585.       the modes and channel of an existing logfile with this command --
  586.       entering a blank mode and channel makes the bot stop logging there
  587.     returns: filename of logfile created, or (if no logfile is specified) a
  588.       list of logfiles like: "{mco * eggdrop.log} {jp #lame lame.log}"
  589.  
  590.   maskhost <nick!user@host>
  591.     returns: hostmask for the string given ("n!u@1.2.3.4" -> "*!u@1.2.3.*",
  592.       "n!u@lame.com" -> "*!u@lame.com", "n!u@a.b.edu" -> "*!u@*.b.edu")
  593.  
  594.   timer <minutes> <tcl-command>
  595.     executes the tcl command after a certain number of minutes have passed
  596.     returns: a timerID
  597.  
  598.   utimer <seconds> <tcl-command>
  599.     executes the tcl command after a certain number of seconds have passed
  600.     returns: a timerID
  601.  
  602.   timers
  603.     returns: list of active minutely timers; each entry in the list contains
  604.       the number of minutes left till activation, the command that will be
  605.       executed, and the timerID
  606.  
  607.   utimers
  608.     returns: list of active secondly timers, identical in format to the
  609.       output from 'timers'
  610.  
  611.   killtimer <timerID>
  612.     removes a minutely timer from the list
  613.     returns: nothing
  614.  
  615.   killutimer <timerID>
  616.     removes a secondly timer from the list
  617.     returns: nothing
  618.  
  619.   unixtime
  620.     returns: a long integer which is the current time according to unix
  621.  
  622.   time
  623.     returns: the current time in 24-hour format (ie "14:15")
  624.  
  625.   date
  626.     returns: the current date in standard format (ie "21 Dec 1994")
  627.  
  628.   ctime <unixtime>
  629.     returns: a string of the date/time represented by the unix time given
  630.       (ie "Fri Aug  3 11:34:55 1973")
  631.  
  632.   myip
  633.     returns: a long number representing the bot's IP address, as it might
  634.       appear in (for example) a DCC request
  635.  
  636.   rand <limit>
  637.     returns: a random integer between 0 and limit-1  
  638.  
  639.   control <idx> <command>
  640.     removes a user from the party line and sends all future input from them
  641.       to the Tcl command given; the command will be called with two parameters:
  642.       the idx of the user, and the input text; the command should return "0"
  643.       to indicate success and "1" to indicate that it relinquishes control of
  644.       the user back to the bot; the idx must be for a user in the party line
  645.       area or the file area; if the input text is blank (""), it indicates
  646.       that the dcc user has dropped connection
  647.     returns: nothing
  648.  
  649.   sendnote <from> <to> <message>
  650.     simulates what happens when one user sends a note to another (this can
  651.       also do cross-bot notes)
  652.     returns: "1" if the note was delivered locally or sent to another bot,
  653.       "2" if the note was stored locally, "3" if the user's notebox is too
  654.       full to store a note, "4" if a Tcl binding caught the note, "5" if
  655.       the note was stored because the user is away, or "0" if the send failed
  656.  
  657.   link [via-bot] <bot>
  658.     attempts to link to another bot directly (or, if you give a via-bot,
  659.       it tells the via-bot to try
  660.     returns: "1" if it looks okay and it will try; "0" if not
  661.  
  662.   unlink <bot>
  663.     attempts to remove a bot from the botnet
  664.     returns: "1" if it will try or has passed the request on; "0" if not
  665.  
  666.   encrypt <key> <string>
  667.     returns: encrypted string (using blowfish), encoded into ascii using
  668.       base-64 so it can be sent over the botnet
  669.  
  670.   decrypt <key> <encrypted-base64-string>
  671.     returns: decrypted string (using blowfish)
  672.  
  673.   die [reason]
  674.     causes the bot to log a fatal error and exit completely; if no reason
  675.     is given, "EXIT" is used
  676.  
  677.  
  678. GLOBAL VARIABLES:
  679.   (All config-file variables are global, too.  But these three variables
  680.   are set by the bot.)
  681.  
  682.   botnick
  683.     current nickname the bot is using, ie 'Valis' or 'Valis0', etc
  684.  
  685.   botname
  686.     current nick!user@host that the server sees, ie 'Valis!valis@crappy.com'
  687.  
  688.   server
  689.     current server the bot is using, ie 'irc.math.ufl.edu:6667'
  690.  
  691.   version
  692.     current bot version (ie: "1.0k 1200"); first item is the text version,
  693.       second item is a numerical version, and any following items are the
  694.       names of patches that have been added
  695.  
  696.   uptime
  697.     unixtime value for when the bot was started
  698.  
  699.   
  700. COMMAND EXTENSION:
  701.  
  702. You can use the 'bind' command to attach Tcl procedures to certain events.
  703. For example, you can write a Tcl procedure that gets called every time a
  704. user says "danger" on the channel.  The following is a list of the types of
  705. bindings, and how they work.  Under each binding type is the format of the
  706. bind command, the list of arguments sent to the Tcl proc, and an explanation.
  707.  
  708. Some bindings are marked as "stackable".  That means that you can bind
  709. multiple commands to the same trigger.  Normally, for example, a binding
  710. of "bind msg - stop msg_stop" (which makes a msg-command "stop" call the
  711. Tcl proc "msg_stop") will overwrite any previous binding you had for the
  712. msg-command "stop".  With stackable bindings, like 'msgm' for example,
  713. you can bind to the same command or mask again and again.  When the
  714. binding is triggered, ALL the Tcl procs that are bound to it will be
  715. called, one after another.
  716.  
  717. To remove a binding, use "unbind".  For example, to remove that binding
  718. for the msg-command "stop", use "unbind msg - stop msg_stop". 
  719.  
  720.  
  721.   (1)  MSG
  722.        bind msg <flags> <command> <proc>
  723.        procname <nick> <user@host> <handle> <args>
  724.  
  725.        used for /msg commands; the first word of the user's msg is the
  726.        command, and everything else becomes the argument string
  727.  
  728.   (2)  DCC
  729.        bind dcc <flags> <command> <proc>
  730.        procname <handle> <idx> <args>
  731.  
  732.        used for commands from a dcc chat on the party line; as in MSG, the
  733.        command is the first word and everything else is the argument string;
  734.        the idx is valid until the user disconnects; after that it may be
  735.        reused, to be careful about storing an idx for long periods of time
  736.  
  737.   (3)  FIL
  738.        bind fil <flags> <command> <proc>
  739.        procname <handle> <idx> <args>
  740.  
  741.        the same as DCC, except this is triggered if the user is in the file
  742.        area instead of the party line
  743.  
  744.   (4)  PUB
  745.        bind pub <flags> <command> <proc>
  746.        procname <nick> <user@host> <handle> <channel> <args>
  747.  
  748.        used for commands given on a channel; just like MSG, the first word
  749.        becomes the command and everything else is the argument string
  750.  
  751.   (5)  MSGM   (stackable)
  752.        bind msgm <flags> <mask> <proc>
  753.        procname <nick> <user@host> <handle> <text>
  754.  
  755.        matches the entire line of text from a /msg with the mask; this is
  756.        more useful for binding Tcl procs to words or phrases spoken anywhere
  757.        within a line of text
  758.  
  759.   (6)  PUBM   (stackable)
  760.        bind pubm <flags> <mask> <proc>
  761.        procname <nick> <user@host> <handle> <channel> <text>
  762.   
  763.        just like MSGM, except it's triggered by things said on a channel
  764.        instead of things /msg'd to the bot; the mask is matched against
  765.        the channel name followed by the text, ie, "#nowhere hello there!",
  766.        and can contain wildcards
  767.  
  768.   (7)  NOTC   (stackable)
  769.        bind notc <flags> <mask> <proc>
  770.        procname <nick> <user@host> <handle> <text>
  771.  
  772.        matches the entire line of text from a /notice with the mask; it
  773.        is considered a breach of protocol to respond to a /notice on IRC,
  774.        so this is intended for internal use (ie, logging, etc) only
  775.  
  776.   (8)  JOIN   (stackable)
  777.        bind join <flags> <mask> <proc>
  778.        procname <nick> <user@host> <handle> <channel>
  779.   
  780.        triggered by someone joining the channel; the <mask> in the bind
  781.        is matched against "#channel nick!user@host" and can contain
  782.        wildcards
  783.  
  784.   (9)  PART   (stackable)
  785.        bind part <flags> <mask> <proc>
  786.        procname <nick> <user@host> <handle> <channel>
  787.  
  788.        triggered by someone leaving the channel; as in JOIN, the <mask>
  789.        is matched against "#channel nick!user@host" and can contain
  790.        wildcards
  791.  
  792.   (10) SIGN   (stackable)
  793.        bind sign <flags> <mask> <proc>
  794.        procname <nick> <user@host> <handle> <channel> <reason>
  795.   
  796.        triggered by a signoff, or possibly by someone who got netsplit and
  797.        never returned; the signoff message is the last argument to the proc;
  798.        wildcards can be used in <mask>, which contains the channel name
  799.  
  800.   (11) TOPC   (stackable)
  801.        bind topc <flags> <mask> <proc>
  802.        procname <nick> <user@host> <handle> <channel> <topic>
  803.  
  804.        triggered by a topic change; can use wildcards in <mask>, which is
  805.        matched against the channel name and new topic
  806.  
  807.   (12) KICK   (stackable)
  808.        bind kick <flags> <mask> <proc>
  809.        procname <nick> <user@host> <handle> <channel> <kicked-nick> <reason>
  810.   
  811.        triggered when someone is kicked off the channel; the <mask> is
  812.        matched against "#channel nick" where the nickname is of the person
  813.        who got kicked off (can use wildcards); the proc is called with
  814.        the nick, user@host, and handle of the kicker, plus the channel,
  815.        the nickname of the person who was kicked, and the reason; <flags>
  816.        is unused here
  817.  
  818.   (13) NICK   (stackable)
  819.        bind nick <flags> <mask> <proc>
  820.        procname <nick> <user@host> <handle> <channel> <newnick>
  821.   
  822.        triggered when someone changes nicknames; wildcards are allowed;
  823.        the mask is matched against "#channel newnick"
  824.  
  825.   (14) MODE   (stackable)
  826.        bind mode <flags> <mask> <proc>
  827.        proc-name <nick> <user@host> <handle> <channel> <mode-change>
  828.   
  829.        mode changes are broken down into their component parts before being
  830.        sent here, so the <mode-change> will always be a single mode, like
  831.        "+m" or "-o snowbot"; flags are ignored; the bot's automatic response
  832.        to a mode change will happen AFTER all matching Tcl procs are called;
  833.        the <mask> will have the channel prefixed (ie, "#turtle +m")
  834.  
  835.   (15) CTCP
  836.        bind ctcp <flags> <keyword-mask> <proc>
  837.        proc-name <nick> <user@host> <handle> <dest> <keyword> <args...>
  838.     
  839.        destination will be a nickname (the bot's nickname, obviously) or
  840.        a channel name; keyword is the ctcp command and args may be empty;
  841.        if the proc returns 0, the bot will attempt its own processing of
  842.        the ctcp command
  843.  
  844.   (16) CTCR
  845.        bind ctcr <flags> <keyword-mask> <proc>
  846.        proc-name <nick> <user@host> <handle> <dest> <keyword> <args...>
  847.  
  848.        just like ctcp, but this is triggered for a ctcp-reply (ie, ctcp
  849.        embedded in a notice instead of a privmsg)
  850.  
  851. | (17) RAW   (stackable)
  852. |      bind raw <flags> <keyword-mask> <proc>
  853. |      procname <from> <keyword> <args...>
  854. |
  855. |      previous versions of eggdrop required a special compile option to
  856. |      enable this binding, but it's now standard; the mask is checked
  857. |      against the keyword (either a numeric like "368" or a keyword like
  858. |      "PRIVMSG"); from will be the server name or the source user (depending
  859. |      on the keyword); flags are ignored; the order of the arguments is
  860. |      identical to the order that the IRC server sends to the bot -- the
  861. |      pre-processing only splits it apart enough to determine the keyword;
  862. |      if the proc returns 1, eggdrop will not process the line any further
  863. |      (THIS COULD CAUSE YOUR BOT TO BEHAVE ODDLY IN SOME CASES)
  864.  
  865.   (18) BOT
  866.        bind bot <flags> <command> <proc>
  867.        proc-name <from-bot> <command> <args>
  868.  
  869.        triggered by a message coming from another bot in the botnet; works
  870.        similar to a DCC binding; the first word is the command and the rest
  871.        becomes the argument string; flags are ignored
  872.  
  873.   (19) CHON   (stackable)
  874.        bind chon <flags> <mask> <proc>
  875.        proc-name <handle> <idx>
  876.  
  877.        when someone first enters the "party-line" area of the bot via dcc
  878.        chat or telnet, this is triggered before they are connected to a
  879.        chat channel (so yes, you can change the channel in a 'chon' proc);
  880.        mask matches against handle; this is NOT triggered when someone
  881.        returns from the file area, etc
  882.  
  883.   (20) CHOF   (stackable)
  884.        bind chof <flags> <mask> <proc>
  885.        proc-name <handle> <idx>
  886.  
  887.        triggered when someone leaves the party line to disconnect from the
  888.        bot; mask matches against the handle; note that the connection may
  889.        have already been dropped by the user, so don't send output to that
  890.        idx
  891.  
  892.   (21) SENT   (stackable)
  893.        bind sent <flags> <mask> <proc>
  894.        proc-name <handle> <nick> <path/to/file>
  895.  
  896.        after a user has successfully downloaded a file from the bot, this
  897.        binding is triggered; mask is matched against the handle of the user
  898.        that initiated the transfer; nick is the actual recipient (on IRC) of
  899.        the file; the path is relative to the dcc directory (unless the file
  900.        transfer was started by a script call to 'dccsend', in which case the
  901.        path is the exact path given in the call to 'dccsend')
  902.  
  903.   (22) RCVD   (stackable)
  904.        bind rcvd <flags> <mask> <proc>
  905.        proc-name <handle> <nick> <path/to/file>
  906.  
  907.        triggered after a user uploads a file successfully; mask is matched
  908.        against the user's handle; nick is the nickname on IRC that the file
  909.        transfer originated from; the path is where the file ended up,
  910.        relative to the dcc directory (usually this is your incoming dir)
  911.  
  912.   (23) CHAT   (stackable)
  913.        bind chat <flags> <mask> <proc>
  914.        proc-name <nick> <channel#> <text>
  915.  
  916.        when someone says something on the botnet, it invokes this binding;
  917.        flags is ignored; nick could be a user on this bot (ie "DronePup")
  918.        or on another bot (ie "Eden@Wilde"); the mask is checked against the
  919.        text
  920.  
  921.   (24) LINK   (stackable)
  922.        bind link <flags> <mask> <proc>
  923.        proc-name <botname> <via>
  924.  
  925.        triggered when a bot links into the botnet; botname is the name of
  926.        the bot that just linked in; via is the bot it linked through; the
  927.        mask is checked against the bot that linked; flags is ignored
  928.  
  929.   (25) DISC   (stackable)
  930.        bind disc <flags> <mask> <proc>
  931.        proc-name <botname>
  932.  
  933.        triggered when a bot disconnects from the botnet for whatever reason;
  934.        just like the link bind, flags are ignored; mask is checked against the
  935.        nickname of the bot that left
  936.  
  937.   (26) SPLT   (stackable)
  938.        bind splt <flags> <mask> <proc>
  939.        procname <nick> <user@host> <handle> <channel>
  940.   
  941.        triggered when someone gets netsplit on the channel; be aware that
  942.        this may be a false alarm (it's easy to fake a netsplit signoff
  943.        message); <mask> may contain wildcards, and is matched against the
  944.        channel and nick!user@host just like join; anyone who is SPLT will
  945.        trigger a REJN or SIGN within the next 15 minutes
  946.  
  947.   (27) REJN   (stackable)
  948.        bind rejn <flags> <nick!user@host> <proc>
  949.        procname <nick> <user@host> <handle> <channel>
  950.  
  951.        someone who was split has rejoined; <mask> can contain wildcards,
  952.        and contains channel and nick!user@host just like join
  953.  
  954. | (28) FILT   (stackable)
  955. |      bind filt <flags> <mask> <proc>
  956. |      procname <idx> <text>
  957. |
  958. |      DCC party line and file system users have their text sent through
  959. |      filt before being processed; if the proc a blank string, the text
  960. |      is considered parsed; otherwise the bot will use the text returned
  961. |      from the proc and continue parsing that
  962.  
  963.   (29) FLUD   (stackable)
  964.        bind flud <flags> <type> <proc>
  965.        procname <nick> <user@host> <handle> <type> <channel>
  966.  
  967.        any floods detected through the flood control settings (like
  968.        'flood-ctcp') are sent here before processing; if the proc
  969.        returns 1, no further action is taken on the flood; if the proc
  970.        returns 0, the bot will do its normal "punishment" for the flood;
  971.        the flood type is "pub", "msg", "join", or "ctcp" (and can be
  972.        masked to "*" for the bind); flags is ignored
  973.  
  974.   (30) NOTE
  975.        bind note <flags> <nickname> <proc>
  976.        procname <from> <to> <text>
  977.  
  978.        incoming notes (either from the party line, someone on IRC, or
  979.        someone on another bot on the botnet) are checked against these
  980.        binds before being process; if a bind exists, the bot will not
  981.        deliver the note; the nickname must be an exact match (no wild-
  982.        cards), but it is not case sensitive; flags is ignored
  983.  
  984.   (31) ACT   (stackable)
  985.        bind act <flags> <mask> <proc>
  986.        proc-name <nick> <channel#> <action>
  987.  
  988.        when someone does an action on the botnet, it invokes this binding;
  989.        flags is ignored; the mask is checked against the text of the
  990.        action (this is very similar to the CHAT binding)
  991.  
  992.  
  993.  
  994. (A) RETURN VALUES
  995.  
  996.     Several bindings pay attention to the value you return from the proc
  997.     (using "return $value").  Usually they expect a 0 or 1, and failing
  998.     to return any value is interpreted as a 0.
  999.  
  1000.     Here's a list of the bindings that use the return value from procs
  1001.     they trigger:
  1002.  
  1003.     MSG   Return 1 to make the command get logged like so:
  1004.           (nick!user@host) !handle! command
  1005.  
  1006.     DCC   Return 1 to make the command get logged like so:
  1007.           #handle# command
  1008.  
  1009.     FIL   Return 1 to make the command get logged like so:
  1010.           #handle# files: command
  1011.  
  1012.     PUB   Return 1 to make the command get logged like so:
  1013.           <<nick>> !handle! command
  1014.  
  1015.     CTCP  Return 1 to ask the bot not to process the CTCP command on its
  1016.           own.  Otherwise it would send its own response to the CTCP
  1017.           (possibly an error message if it doesn't know how to deal with
  1018.           it).
  1019.  
  1020.     FILT  Return 1 to indicate the text has been processed, and the bot
  1021.           should just ignore it.  Otherwise it will treat the text like
  1022.           any other.
  1023.  
  1024.     FLUD  Return 1 to ask the bot not to take action on the flood.
  1025.           Otherwise it will do its normal punishment.
  1026.  
  1027.     RAW   Return 1 to ask the bot not to process the server text.  This
  1028.           can affect the bot's performance (by causing it to miss things
  1029.           that it would normally act on) -- you have been warned.
  1030.  
  1031.  
  1032. (B) CONTROL PROCEDURES
  1033.  
  1034.     Using the 'control' command you can put a DCC connection (or outgoing
  1035.     TCP connection) in control of a script.  All text that comes in on
  1036.     the connection is sent to the proc you specify.  All outgoing text
  1037.     should be sent with 'putdcc'.
  1038.  
  1039.     The control procedure is called with these parameters:
  1040.        procname <idx> <input-text>
  1041.     This allows you to use the same proc for several connections.  The
  1042.     idx will stay the same until the connection is dropped -- after that,
  1043.     it will probably get reused for a later connection.
  1044.  
  1045.     To indicate that the connection has closed, your control procedure
  1046.     will be called with blank text (the input-text will be "").  This
  1047.     is the only time it will ever be called with "" as the text, and it
  1048.     is the last time your proc will be called for that connection.
  1049.  
  1050.     If you want to hand control of your connection back to eggdrop, your
  1051.     proc should return 1.  Otherwise, return 0 to retain control.
  1052.  
  1053.  
  1054. (C) TCP CONNECTIONS
  1055.  
  1056.     Eggdrop allows you to make two types of TCP ("telnet") connections:
  1057.     outgoing and incoming.  For an outgoing connection, you specify the
  1058.     remote host and port to connect to.  For an incoming connection,
  1059.     you specify a port to listen at.
  1060.  
  1061.     All of the connections are *event driven*.  This means that the bot
  1062.     will trigger your procs when something happens on the connection,
  1063.     and your proc is expected to return as soon as possible.  Waiting
  1064.     in a proc for more input is a no-no.
  1065.  
  1066.     To initiate an outgoing connection, use:
  1067.        set idx [connect "hostname.goes.here" 3333]
  1068.     (as an example).  $idx now contains a new DCC entry for the outgoing
  1069.     connection.
  1070.  
  1071.     All connections use non-blocking (commonly called "asynchronous",
  1072.     which is a misnomer) I/O.  Without going into a big song and dance
  1073.     about asynchronous I/O, what this means to you is:
  1074.  
  1075.     * assume the connection succeeded immediately
  1076.     * if the connection failed, an EOF will arrive for that idx
  1077.  
  1078.     The only time a 'connect' call will return an error is if you gave
  1079.     a hostname and it couldn't find the IP for that hostname (this is
  1080.     considered a "DNS error").  Otherwise it will appear to have succeeded,
  1081.     and if the connection failed, you will immediately get an EOF.
  1082.  
  1083.     Right after doing a 'connect' call, you should set up a 'control' for
  1084.     the new idx (see the section above).  From then on, the connection
  1085.     will act just like a normal DCC connection that has been put under
  1086.     the control of a script.  If you ever return "1" from the control
  1087.     proc (indicating that you want control to return to eggdrop), the bot
  1088.     will just close the connection and dispose of it.  Other commands
  1089.     that work on normal DCC connections, like 'killdcc' and 'putdcc', 
  1090.     will work on this idx too.
  1091.  
  1092.     To create a listening port, use:
  1093.        listen 6667 script grabproc
  1094.     which will create a new listening port at 6667, and assign it to the
  1095.     script 'grabproc'.
  1096.  
  1097.     When a new connection arrives, eggdrop will connect it up and create
  1098.     a new idx for the connection.  That idx is sent to 'grabproc'.  The
  1099.     proc will generally want to immediately put this idx under control:
  1100.        proc grabproc {newidx} {
  1101.          control $newidx my_control
  1102.        }
  1103.     Once your grabproc has been called, the idx behaves exactly like an
  1104.     outgoing connection would.
  1105.  
  1106.     The best way to learn how to use these commands is to find a script
  1107.     that uses them and follow it carefully.  Hopefully this has given you
  1108.     a good start though.
  1109.  
  1110.  
  1111. (D) MATCH CHARACTERS
  1112.  
  1113.     Many of the bindings allow match characters in the arguments.  Here
  1114.     are the four special characters:
  1115.  
  1116.     ?  matches any single character
  1117.     *  matches 0 or more characters of any type
  1118.     %  matches 0 or more non-space characters (can be used to match a
  1119.           single word)
  1120.     ~  matches 1 or more space characters (can be used for whitespace
  1121.           between words)
  1122.  
  1123.